home *** CD-ROM | disk | FTP | other *** search
/ Aminet 19 / Aminet 19 (1997)(GTI - Schatztruhe)[!][Jun 1997].iso / Aminet / comm / cnet / time_clock.lha / timerclock / TimeClock.README < prev    next >
Text File  |  1997-03-13  |  16KB  |  319 lines
  1. ============================================================================
  2.     TimerClock, v2.00; THE Replacement for your "T" Command, by Dotoran!
  3. ============================================================================
  4.  
  5. What is it?
  6. ~~~~~~~~~~~
  7.     This program is a program you can use in place of your "T" command, or
  8. as a stand alone door object. It uses the BIG NUMBERS that my previous
  9. "BIG_CPS_Speed" door used. There is also an ASCII equivalent built into the
  10. program. To see exactly what this programs output looks like, add it into
  11. your DOORS: directory as a standard Arexx program file and run it.
  12.  
  13.     Additionally, v2.00 of TimerClock introduces the "Time Clock Extensions",
  14. which are TIMERS the users can use to be alerted when either a specific period
  15. of time has gone by, or when a specific TIME occurs.
  16.  
  17. How to Install?
  18. ~~~~~~~~~~~~~~~
  19. 1. Move the included "TimerClock/" directory somewhere in your system. I
  20.    would suggest somewhere in your DOORS: area. Make sure you leave all 
  21.    files IN this directory, but WHERE you decide to place this directory 
  22.    is purely up to you!
  23.  
  24. 2. You can opt to run this door either as a stand alone door object, or in
  25.    place of your "T"ime command. If you'd like to replace the existing TIME
  26.    command with the "TimeClock", then make these changes to your BBSTEXT
  27.    file, as described for each specific version of CNet Amiga:
  28.  
  29.    CNet Amiga, v4.25a+ SysOps
  30.    ~~~~~~~~~~~~~~~~~~~~~~~~~~
  31.       Locate line 283 in your bbstext file. It looks like this in the stock
  32.       v4.25a version:
  33.  
  34.             \n1This is your %d%s call, the system's %d%s.\n1
  35.  
  36.       To suppress text output from the bbstext file, you need to comment out
  37.       lines 283 thru 293 by enclosing each of these lines within the comment
  38.       MCI container. Start each line with a "{;"  (minus the quotes, where
  39.       the { is a Control-Q character), and end each line with a "}" symbol.
  40.       (Again, minus the quotes, but as the standard right brace character).
  41.  
  42.       When complete, the lines would look like the following (using stock
  43.       4.25a original line contents):
  44.  
  45. Line 283:   {;\n1This is your %d%s call, the system's %d%s.\n1}
  46. Line 284:   {;\n1This is your %d%s call today}
  47. Line 285:   {;; %d remaining.\n1}
  48. Line 286:   {;.\n1}
  49. Line 287:   {;\n1Logon:  %s\n1}
  50. Line 288:   {;Now  :  %s\n2}
  51. Line 289:   {;Minutes online     :     %3d.%1d\n1}
  52. Line 290:   {;Remaining today    :     %3d.%1d\n1}
  53. Line 291:   {;Remaining this call:}
  54. Line 292:   {; TOO MUCH!\n1}
  55. Line 293:   {;    %3d.%1d\n1}
  56.             ^^
  57. Control-Q --'`-- Semicolon
  58.  
  59.       Control-Y characters in the above lines were changed to \'s to help
  60.       readability in this document. If you copy and paste the above lines, 
  61.       make sure to convert ALL \'s to Control-Y's and the {'s to Control-Q's.
  62.       No actual {'s or \'s appear anywhere on these lines.
  63.  
  64.     CNet Amiga, v3.05c SysOps
  65.     ~~~~~~~~~~~~~~~~~~~~~~~~~
  66.       Your version of CNet does not have the Comment MCI command, so you'll
  67.       have to do the following instead:
  68.  
  69.       REPLACE the contents of lines 283 thru 293 with a Control-Q character,
  70.       followed directly by a right brace character. The lines in YOUR bbstext
  71.       file would then look like the following:
  72.  
  73. Line 283:   {}
  74. Line 284:   {}
  75. Line 285:   {}
  76. Line 286:   {}
  77. Line 287:   {}
  78. Line 288:   {}
  79. Line 289:   {}
  80. Line 290:   {}
  81. Line 291:   {}
  82. Line 292:   {}
  83. Line 293:   {}
  84.             ^
  85.         Control-Q
  86.  
  87.     Completing Step # 2
  88.     ~~~~~~~~~~~~~~~~~~~
  89.       Once the appropriate changes have been made to lines 283 thru 293 per
  90.       your specific version of CNet Amiga, do the following to finish up the
  91.       needed bbstext change:
  92.  
  93.       Insert the following IN FRONT of the text found on line 283. 
  94.  
  95.       The finished line looks like the following in CNet Amiga, v4.25a:
  96.  
  97.         {#0<path>TimerClock/TimeClock}{;\n1This is your %d%s call... etc
  98.         ^                             ^ ^                                            ^
  99.         `--> Control-Q Characters <---' `-----> Control-Y character
  100.  
  101.       And like this in CNet Amiga, v3.05c:
  102.  
  103.         {#0<path>TimerClock/TimeClock}{}
  104.         ^                             ^
  105.         `--> Control-Q Characters <---'
  106.  
  107.       Replace <path> above with the location you chose to store the 
  108.       "TimerClock/" directory in Step # 1 above.
  109.  
  110. 3. If you'd like to use the "Time Clock Extensions", which presently include
  111.    the two forms of TIMERS, you'll need to add the following to the END of
  112.    line 62 in bbstext. The completed line looks like this:
  113.  
  114.         \n1@ Cleared for logon\n1{#0<path>TimerClock/TimeClockP}
  115.         ^                     ^  ^
  116.         `---- Control-Y's ----'  `-- A Control-Q character.
  117.  
  118.    You may notice other pfile/door launch commands on this line as well, if
  119.    you've added certain other enhancements to your system. Simply add the
  120.    call to "TimeClockP" to the END of whatever else appears on that line.
  121.  
  122.    Also remember to replace the <path> with the full path you chose to store
  123.    the "TimerClock/" directory in Step # 1 above.
  124.  
  125. 4. To further customize how the Time Clock looks, you can edit the variables
  126.    located near the start of the "TimeClock" file. Briefly, here's what the
  127.    different variables do:
  128.  
  129.    v1 : Contains FIVE (5) MCI Color Codes, each separated by ONE (1) Space.
  130.         These codes define the colors to use when displaying "Current Time"
  131.  
  132.         1st: Color of text "Current Time".
  133.         2nd: Color of colon after text above.
  134.         3rd: Color of BIG Numbers used for HOURS and MINUTES.
  135.         4th: Color of BIG Colon BETWEEN above BIG Numbers.
  136.         5th: Color of BIG Letters AM (or PM) displayed AFTER the Time.
  137.              Note: If time is to be displayed in 24 Hour Format, the output
  138.                    of AM/PM will be suppressed, however you will still need
  139.                    to supply a color code within this variable anyways.
  140.  
  141.    v2 : Contains FIVE (5) MCI Color Codes, each separated by ONE (1) Space.
  142.         These codes define the colors to use when displaying "Logon Time"
  143.  
  144.         1st: Color of text "Your Logon Time".
  145.         2nd: Color of colon after text above.
  146.         3rd: Color of BIG Numbers used for HOURS and MINUTES.
  147.         4th: Color of BIG Colon BETWEEN above BIG Numbers.
  148.         5th: Color of BIG Letters AM (or PM) displayed AFTER the Time.
  149.              Note: If time is to be displayed in 24 Hour Format, the output
  150.                    of AM/PM will be suppressed, however you will still need
  151.                    to supply a color code within this variable anyways.
  152.  
  153.    v3 : Contains THREE (3) MCI Color Codes, each separated by ONE (1) Space.
  154.         These codes define the colors to use when displaying "Minutes Online"
  155.  
  156.         1st: Color of text "Minutes Online".
  157.         2nd: Color of colon after text above.
  158.         3rd: Color of BIG Numbers used to display MINUTES.
  159.  
  160.    v4 : Contains EIGHT (8) MCI Color Codes, each separated by ONE (1) Space.
  161.         These codes define the colors to use when displaying the text and 
  162.         values that appear at the BOTTOM of the display.
  163.  
  164.         1st: Color of all "regular" text.
  165.         2nd: Color of the value of "Your Total Calls".
  166.         3rd: Color of the value of "Total System Calls".
  167.         4th: Color of the text "Total Calls"
  168.         5th: Color of the NAME of the BBS. (Name plucked from "bbsconfig3/4")
  169.         6th: Color of the value of "Total Minutes Left This Call".
  170.         7th: Color of parenthesis surrounding text "enter".
  171.         8th: Color of the text "enter".
  172.  
  173.    v5 : This is a string of SPACES. This is the gutter that'll be used between
  174.         each of the BIG Characters displayed on the screen. As set by default,
  175.         there will be TWO (2) spaces placed between each BIG Character. Play
  176.         around with this setting until you find the one you like best.
  177.  
  178.    te : Should be set to a 0, or a 1, dependent on if you'd like the user to
  179.         be asked if they wish to use the TIMERS after the time display has
  180.         been completed. Set to "0" and the user will be placed back at the
  181.         command prompt. Set to "1" and they'll be shown a request like the
  182.         following:
  183.  
  184.             Set <C>ount-Down Timer, <T>ime-Of-Day Timer, or [QUIT]:
  185.  
  186. 5. To view the ASCII display used within TimeClock, the local SysOp will need
  187.    to set their "Graphic Set" to ASCII using the ET command. After which, by
  188.    using the "T"ime command, you'll be shown the ASCII representation of the
  189.    Time Clock. Use the ET command to switch back to IBM/ANSI when you're
  190.    through checking the ASCII look of the Time Clock.
  191.  
  192. 6. If the "te" variable is set to a "1" in Step # 4 above, you'll be giving
  193.    your users access to a VALUABLE little tool. The timers themselves will
  194.    be explained more fully below, however you can also add a series of
  195.    additional commands that can be used to DIRECTLY launch the timers,
  196.    without the need to view the Time Clock first. If this interests you,
  197.    then please add one or more of the following lines to the END of your
  198.    Menu # 2; Available Everywhere in your BBSMENU file:
  199.  
  200.         TIMERs                  `3-  | {#0<path>TimerClock/TimeClockE 1}
  201.         CDT, Count Down Timer   `3-  | {#0<path>TimerClock/TimeClockE C}
  202.         TDT, Time of Day Timer  `3-  | {#0<path>TimerClock/TimeClockE T}
  203.                                  ^     ^
  204.                 Access Groups ---'     `--- Control-Q characters.
  205.  
  206.    Replace <path> above with the same one used in Step # 1 above.
  207.  
  208.    The CASE of the letters used for the commands is VERY important. Make sure
  209.    to capitalize the ENTIRE word TIMER, else your existing TIME command will
  210.    kick in. Also, missing the T in CDT will cause problems when using the CD
  211.    command in File Exchange Bases. Lastly, the "of" in the TDT command should
  212.    NOT be capitalized.
  213.  
  214. 7. That's it! Save, then Reload both your BBSTEXT and BBSMENU files and you'll
  215.    be ready to utilize this program!
  216.  
  217. Using the Timers
  218. ~~~~~~~~~~~~~~~~
  219.     There are two types of timers included in this first release. One is
  220. referred to as a "Count Down" timer, and operates just like a Cooking Timer,
  221. where it "ticks" off a specified number of minutes. The other is referred to
  222. as a "Time of Day" timer. This timer operates like an Alarm Clock, where you
  223. specify a specific TIME during the day. Minutes are ticked off until this
  224. time comes about, to which the timer goes off.
  225.  
  226.     When a timer expires, a SYSTEM OLM message will be sent to the user. What
  227. makes these timers really powerful are three specific features:
  228.  
  229. 1. They generate SYSTEM OLM messages. These OLM messages WILL be shown to the
  230.    user, even if they are in a "muffled" location, however in the muffled
  231.    state, the OLM is put on "hold" until such a time as the user unmuffles
  232.    themselves. (Unlike regular and broadcast OLM messages which are actually
  233.    thrown away if the user is muffled).
  234.  
  235. 2. The timers STAY IN EFFECT if the user should happen to lose carrier, or
  236.    have to log off, then back on. Provided the user logs back on WITHIN the
  237.    set time frame stated in the creation of the timer, they WILL be shown the
  238.    "Alarm OLM Message".
  239.  
  240. 3. If a user loses carrier, or logs off, as stated above, and then logs back
  241.    on, but to a DIFFERENT PORT, they STILL will receive their Alarm OLM. The
  242.    original program my version was modeled after was LACKING this ability.
  243.    This ability comes in VERY handy when coupled with multi-line systems that
  244.    use HUNT groups of phone lines, as in these instances, it is impossible
  245.    for the USER to know WHICH port they'll get connected to, which isn't much
  246.    of a relief for the user who created a timer event in the first place!
  247.  
  248.     Another feature that was MISSING from the original was the ability of the
  249. program to know if a timer had already been set, as well as the ability of
  250. being able to CANCEL a timer event, in case it was no longer needed. This
  251. version attacks both of these issues.
  252.  
  253.     When a user launches one of the timers, they'll be asked for two pieces
  254. of informtion. The first is the number of minutes, or the time of day, to
  255. which they'd like the timer to "go off", while the second is an optional line
  256. of text referred to as the "reminder". This comes in handy when you wish to
  257. enter a reason for setting the timer in the first place. If entered, this text
  258. is included in the OLM message that is created and sent as the "alarm".
  259.  
  260.     With the information obtained, the timer script launches a background
  261. script that simply sits around ticking off the seconds, while allowing the
  262. user to go about their regular business. When the background task notes that
  263. the appropriate time has come, it checks the status of the event(is the user
  264. still online, is the timer still valid(ie, it wasn't canceled, was it?), and
  265. if the user is still on the same port). If it is seen that the user is logged
  266. on to  different port, then the proper adjustments are made before continuing.
  267. If the status tests positive, then the appropriate OLM message is constructed
  268. and sent to the correct port, after which the timer event is canceled and the
  269. background task terminates. The background task uses ARexx's DELAY() function
  270. to tick off the time. This method is the accepted way for counting off time, 
  271. and does NOT prove to be a burden on the rest of your system.
  272.  
  273.     This program uses both background ARexx tasks as well as Clip Variables
  274. to complete it's operation. Timers will stay in effect in ALL instances
  275. EXCEPT in the event the system reboots. In this case, all timer events will
  276. be lost. No external data files are created during the use of this program.
  277. In the next release, I'll include the ability to NEVER lose a timer event,
  278. even IF the system needs to reboot itself!
  279.  
  280. That's It! Acknowledgements, Bug Reports, etc.
  281. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  282.     Well, that's all there is! I hope I wasn't TOO long winded in my attempt
  283. to explain what the file does. It's fairly straight forward, but I wanted to
  284. give a bit more info for those that might have been interested in knowing 
  285. just HOW the file is able to do what it does. ;-)
  286.  
  287.     The "original" program I was referring to was a little utility written
  288. by Aunt Bea of The Blue Moon BBS. He wrote a similar utility for use on his
  289. system awhile ago and I happened upon it the one day and really liked it's
  290. premise. I've asked Bea numerous times to release some of his files to the
  291. public, as he really DOES write some great little tidbits, but as of yet,
  292. he's declined to release anything to date. (We can hope!).
  293.  
  294.     The idea of coupling the timers with the Time Clock was mine completely.
  295. I thought it would make a real nice enhancement to an already real nice little
  296. tool! As mentioned above, I've eluded to the fact that there will be at LEAST
  297. one more included "extension" sometime in the future, but I'll keep you all
  298. guessing as to what this NEW little extension will do!
  299.  
  300.     Anyways, the included programs were all completely written from scratch
  301. by myself, so I could be sure as to what EXACTLY they were doing. I also
  302. wanted(no, NEEDED! hehe) to add those specific features I saw as lacking in
  303. Bea's version, so I hope you all like them as well!
  304.  
  305.     As always, if you find fault with any of these programs, please do not
  306. hesitate to send them my way and I'll try my best to tackle them all...
  307.  
  308.                          Dave Weeks, aka Dotoran
  309.  
  310.                 FidoNet> dotoran@1:260/121.0
  311.                CLinkNet> dotoran@911:6840/2.0
  312.                ChipsNet> dotoran@546:7/1.0
  313.                InterNet> dotoran@bluemoon.net
  314.            WorldWideWeb> http://www.bluemoon.net/~dotoran/email.htm
  315.  
  316. ============================================================================
  317.    Feeling Hot? Catch My Waves Today!   http://www.bluemoon.net/~dotoran
  318. ============================================================================
  319.